خصائص SQLAlchemy الهجينة في بايثون: سمات محسوبة لنمذجة بيانات قوية

تقدم SQLAlchemy، وهي مجموعة أدوات Python SQL قوية ومرنة ومخطط علاقي كائني (ORM)، مجموعة غنية من الميزات للتفاعل مع قواعد البيانات. من بين هذه الميزات، تبرز الخصائص الهجينة (Hybrid Properties) كأداة مفيدة بشكل خاص لإنشاء سمات محسوبة داخل نماذج البيانات الخاصة بك. يقدم هذا المقال دليلاً شاملاً لفهم واستخدام خصائص SQLAlchemy الهجينة، مما يتيح لك بناء تطبيقات أكثر تعبيرًا وقابلية للصيانة وكفاءة.

ما هي خصائص SQLAlchemy الهجينة؟

الخاصية الهجينة، كما يوحي اسمها، هي نوع خاص من الخصائص في SQLAlchemy يمكن أن تتصرف بشكل مختلف اعتمادًا على السياق الذي يتم الوصول إليها فيه. تتيح لك تحديد سمة يمكن الوصول إليها مباشرة على كائن من فئتك (مثل خاصية عادية) أو استخدامها في تعبيرات SQL (مثل عمود). يتم تحقيق ذلك عن طريق تحديد دوال منفصلة لكل من الوصول على مستوى الكائن وعلى مستوى الفئة.

في جوهرها، توفر الخصائص الهجينة طريقة لتعريف السمات المحسوبة المشتقة من سمات أخرى في نموذجك. يمكن استخدام هذه السمات المحسوبة في الاستعلامات، ويمكن أيضًا الوصول إليها مباشرة على كائنات نموذجك، مما يوفر واجهة متسقة وبديهية.

لماذا نستخدم الخصائص الهجينة؟

يقدم استخدام الخصائص الهجينة العديد من المزايا:

• التعبيرية: تتيح لك التعبير عن العلاقات والحسابات المعقدة مباشرة داخل نموذجك، مما يجعل الكود الخاص بك أكثر قابلية للقراءة وأسهل للفهم.
• القابلية للصيانة: من خلال تغليف المنطق المعقد داخل الخصائص الهجينة، فإنك تقلل من تكرار الكود وتحسن من قابلية صيانة تطبيقك.
• الكفاءة: تتيح لك الخصائص الهجينة إجراء العمليات الحسابية مباشرة في قاعدة البيانات، مما يقلل من كمية البيانات التي تحتاج إلى نقلها بين تطبيقك وخادم قاعدة البيانات.
• الاتساق: توفر واجهة متسقة للوصول إلى السمات المحسوبة، بغض النظر عما إذا كنت تعمل مع كائنات نموذجك أو تكتب استعلامات SQL.

مثال أساسي: الاسم الكامل

لنبدأ بمثال بسيط: حساب الاسم الكامل للشخص من اسمه الأول واسم عائلته.

تحديد النموذج

أولاً، نحدد نموذج `Person` بسيطًا يحتوي على عمودي `first_name` و `last_name`.

from sqlalchemy import create_engine, Column, Integer, String
from sqlalchemy.ext.declarative import declarative_base
from sqlalchemy.orm import sessionmaker
from sqlalchemy.ext.hybrid import hybrid_property

Base = declarative_base()

class Person(Base):
    __tablename__ = 'people'
    id = Column(Integer, primary_key=True)
    first_name = Column(String)
    last_name = Column(String)

    def __repr__(self):
        return f""


engine = create_engine('sqlite:///:memory:') # قاعدة بيانات في الذاكرة للمثال
Base.metadata.create_all(engine)
Session = sessionmaker(bind=engine)
session = Session()

إنشاء الخاصية الهجينة

الآن، سنضيف خاصية `full_name` الهجينة التي تدمج الاسم الأول واسم العائلة.

class Person(Base):
    __tablename__ = 'people'
    id = Column(Integer, primary_key=True)
    first_name = Column(String)
    last_name = Column(String)

    @hybrid_property
    def full_name(self):
        return f"{self.first_name} {self.last_name}"

    def __repr__(self):
        return f""

في هذا المثال، يحول المزخرف `@hybrid_property` دالة `full_name` إلى خاصية هجينة. عند الوصول إلى `person.full_name`، سيتم تنفيذ الكود الموجود داخل هذه الدالة.

الوصول إلى الخاصية الهجينة

لنقم بإنشاء بعض البيانات ونرى كيفية الوصول إلى خاصية `full_name`.

person1 = Person(first_name='Alice', last_name='Smith')
person2 = Person(first_name='Bob', last_name='Johnson')

session.add_all([person1, person2])
session.commit()

print(person1.full_name)  # الناتج: Alice Smith
print(person2.full_name)  # الناتج: Bob Johnson

استخدام الخاصية الهجينة في الاستعلامات

تظهر القوة الحقيقية للخصائص الهجينة عند استخدامها في الاستعلامات. يمكننا التصفية بناءً على `full_name` كما لو كان عمودًا عاديًا.

people_with_smith = session.query(Person).filter(Person.full_name == 'Alice Smith').all()
print(people_with_smith) # الناتج: []

ومع ذلك، فإن المثال أعلاه سيعمل فقط لعمليات التحقق البسيطة من المساواة. للعمليات الأكثر تعقيدًا في الاستعلامات (مثل `LIKE`)، نحتاج إلى تحديد دالة تعبير.

تحديد دوال التعبير

لاستخدام الخصائص الهجينة في تعبيرات SQL أكثر تعقيدًا، تحتاج إلى تحديد دالة تعبير. تخبر هذه الدالة SQLAlchemy بكيفية ترجمة الخاصية الهجينة إلى تعبير SQL.

لنعدل المثال السابق لدعم استعلامات `LIKE` على خاصية `full_name`.

from sqlalchemy import func

class Person(Base):
    __tablename__ = 'people'
    id = Column(Integer, primary_key=True)
    first_name = Column(String)
    last_name = Column(String)

    @hybrid_property
    def full_name(self):
        return f"{self.first_name} {self.last_name}"

    @full_name.expression
    def full_name(cls):
        return func.concat(cls.first_name, ' ', cls.last_name)

    def __repr__(self):
        return f""

هنا، أضفنا المزخرف `@full_name.expression`. يحدد هذا دالة تأخذ الفئة (`cls`) كوسيط وتعيد تعبير SQL يدمج الاسم الأول واسم العائلة باستخدام دالة `func.concat`. `func.concat` هي دالة SQLAlchemy تمثل دالة الدمج في قاعدة البيانات (على سبيل المثال، `||` في SQLite، `CONCAT` في MySQL و PostgreSQL).

الآن يمكننا استخدام استعلامات `LIKE`:

people_with_smith = session.query(Person).filter(Person.full_name.like('%Smith%')).all()
print(people_with_smith) # الناتج: []

تعيين القيم: دالة التعيين (Setter)

يمكن أن تحتوي الخصائص الهجينة أيضًا على دوال تعيين (setters)، مما يسمح لك بتحديث السمات الأساسية بناءً على قيمة جديدة. يتم ذلك باستخدام المزخرف `@full_name.setter`.

لنضف دالة تعيين إلى خاصية `full_name` تقوم بتقسيم الاسم الكامل إلى اسم أول واسم عائلة.

class Person(Base):
    __tablename__ = 'people'
    id = Column(Integer, primary_key=True)
    first_name = Column(String)
    last_name = Column(String)

    @hybrid_property
    def full_name(self):
        return f"{self.first_name} {self.last_name}"

    @full_name.expression
    def full_name(cls):
        return func.concat(cls.first_name, ' ', cls.last_name)

    @full_name.setter
    def full_name(self, full_name):
        parts = full_name.split()
        self.first_name = parts[0]
        self.last_name = ' '.join(parts[1:]) if len(parts) > 1 else ''

    def __repr__(self):
        return f""

الآن يمكنك تعيين خاصية `full_name`، وستقوم بتحديث سمتي `first_name` و `last_name`.

person = Person(first_name='Alice', last_name='Smith')
session.add(person)
session.commit()

person.full_name = 'Charlie Brown'
print(person.first_name)  # الناتج: Charlie
print(person.last_name)   # الناتج: Brown

session.commit()

دوال الحذف (Deleters)

على غرار دوال التعيين، يمكنك أيضًا تحديد دالة حذف لخاصية هجينة باستخدام المزخرف `@full_name.deleter`. يتيح لك هذا تحديد ما يحدث عند محاولة `del person.full_name`.

لمثالنا، لنجعل حذف الاسم الكامل يمسح كلاً من الاسم الأول واسم العائلة.

class Person(Base):
    __tablename__ = 'people'
    id = Column(Integer, primary_key=True)
    first_name = Column(String)
    last_name = Column(String)

    @hybrid_property
    def full_name(self):
        return f"{self.first_name} {self.last_name}"

    @full_name.expression
    def full_name(cls):
        return func.concat(cls.first_name, ' ', cls.last_name)

    @full_name.setter
    def full_name(self, full_name):
        parts = full_name.split()
        self.first_name = parts[0]
        self.last_name = ' '.join(parts[1:]) if len(parts) > 1 else ''

    @full_name.deleter
    def full_name(self):
        self.first_name = None
        self.last_name = None

    def __repr__(self):
        return f""

person = Person(first_name='Charlie', last_name='Brown')
session.add(person)
session.commit()

del person.full_name
print(person.first_name) # الناتج: None
print(person.last_name)  # الناتج: None

session.commit()

مثال متقدم: حساب العمر من تاريخ الميلاد

لننظر في مثال أكثر تعقيدًا: حساب عمر الشخص من تاريخ ميلاده. يعرض هذا قوة الخصائص الهجينة في التعامل مع التواريخ وإجراء العمليات الحسابية.

إضافة عمود تاريخ الميلاد

أولاً، نضيف عمود `date_of_birth` إلى نموذج `Person` الخاص بنا.

from sqlalchemy import Date
import datetime

class Person(Base):
    __tablename__ = 'people'
    id = Column(Integer, primary_key=True)
    first_name = Column(String)
    last_name = Column(String)
    date_of_birth = Column(Date)

    # ... (الكود السابق)

حساب العمر باستخدام خاصية هجينة

الآن ننشئ خاصية `age` الهجينة. تحسب هذه الخاصية العمر بناءً على عمود `date_of_birth`. سنحتاج إلى التعامل مع حالة كون `date_of_birth` هي `None`.

from sqlalchemy import Date
import datetime

class Person(Base):
    __tablename__ = 'people'
    id = Column(Integer, primary_key=True)
    first_name = Column(String)
    last_name = Column(String)
    date_of_birth = Column(Date)

    @hybrid_property
    def age(self):
        if self.date_of_birth:
            today = datetime.date.today()
            age = today.year - self.date_of_birth.year - ((today.month, today.day) < (self.date_of_birth.month, self.date_of_birth.day))
            return age
        return None # أو قيمة افتراضية أخرى

    @age.expression
    def age(cls):
        today = datetime.date.today()
        return func.cast(func.strftime('%Y', 'now') - func.strftime('%Y', cls.date_of_birth) - (func.strftime('%m-%d', 'now') < func.strftime('%m-%d', cls.date_of_birth)), Integer)

    # ... (الكود السابق)

اعتبارات هامة:

• دوال التاريخ الخاصة بقاعدة البيانات: تستخدم دالة التعبير `func.strftime` لحسابات التاريخ. هذه الدالة خاصة بـ SQLite. بالنسبة لقواعد البيانات الأخرى (مثل PostgreSQL أو MySQL)، ستحتاج إلى استخدام دوال التاريخ المناسبة الخاصة بقاعدة البيانات (على سبيل المثال، `EXTRACT` في PostgreSQL، `YEAR` و `MAKEDATE` في MySQL).
• تحويل الأنواع (Type Casting): نستخدم `func.cast` لتحويل نتيجة حساب التاريخ إلى عدد صحيح. هذا يضمن أن خاصية `age` تعيد قيمة عددية صحيحة.
• المناطق الزمنية: كن على دراية بالمناطق الزمنية عند التعامل مع التواريخ. تأكد من أن تواريخك مخزنة ومقارنة في منطقة زمنية متسقة.
• التعامل مع قيم `None`: يجب أن تتعامل الخاصية مع الحالات التي يكون فيها `date_of_birth` هو `None` لمنع الأخطاء.

استخدام خاصية العمر

person1 = Person(first_name='Alice', last_name='Smith', date_of_birth=datetime.date(1990, 1, 1))
person2 = Person(first_name='Bob', last_name='Johnson', date_of_birth=datetime.date(1985, 5, 10))

session.add_all([person1, person2])
session.commit()

print(person1.age)  # الناتج: (بناءً على التاريخ الحالي وتاريخ الميلاد)
print(person2.age)  # الناتج: (بناءً على التاريخ الحالي وتاريخ الميلاد)

people_over_30 = session.query(Person).filter(Person.age > 30).all()
print(people_over_30) # الناتج: (الأشخاص الذين تزيد أعمارهم عن 30 بناءً على التاريخ الحالي)

أمثلة وحالات استخدام أكثر تعقيدًا

حساب إجماليات الطلبات في تطبيق تجارة إلكترونية

في تطبيق التجارة الإلكترونية، قد يكون لديك نموذج `Order` مع علاقة بنماذج `OrderItem`. يمكنك استخدام خاصية هجينة لحساب القيمة الإجمالية للطلب.

from sqlalchemy import ForeignKey, Float
from sqlalchemy.orm import relationship

class Order(Base):
    __tablename__ = 'orders'
    id = Column(Integer, primary_key=True)
    items = relationship("OrderItem", back_populates="order")

    @hybrid_property
    def total(self):
        return sum(item.price * item.quantity for item in self.items)

    @total.expression
    def total(cls):
        return session.query(func.sum(OrderItem.price * OrderItem.quantity)).\
            filter(OrderItem.order_id == cls.id).scalar_subquery()

class OrderItem(Base):
    __tablename__ = 'order_items'
    id = Column(Integer, primary_key=True)
    order_id = Column(Integer, ForeignKey('orders.id'))
    order = relationship("Order", back_populates="items")
    price = Column(Float)
    quantity = Column(Integer)

يوضح هذا المثال دالة تعبير أكثر تعقيدًا تستخدم استعلامًا فرعيًا لحساب الإجمالي مباشرة في قاعدة البيانات.

الحسابات الجغرافية

إذا كنت تعمل مع بيانات جغرافية، يمكنك استخدام الخصائص الهجينة لحساب المسافات بين النقاط أو تحديد ما إذا كانت النقطة تقع ضمن منطقة معينة. غالبًا ما يتضمن ذلك استخدام دوال جغرافية خاصة بقاعدة البيانات (مثل دوال PostGIS في PostgreSQL).

from geoalchemy2 import Geometry
from sqlalchemy import cast

class Location(Base):
    __tablename__ = 'locations'
    id = Column(Integer, primary_key=True)
    name = Column(String)
    coordinates = Column(Geometry(geometry_type='POINT', srid=4326))

    @hybrid_property
    def latitude(self):
        if self.coordinates:
            return self.coordinates.x
        return None

    @latitude.expression
    def latitude(cls):
        return cast(func.ST_X(cls.coordinates), Float)

    @hybrid_property
    def longitude(self):
        if self.coordinates:
            return self.coordinates.y
        return None

    @longitude.expression
    def longitude(cls):
        return cast(func.ST_Y(cls.coordinates), Float)

يتطلب هذا المثال ملحق `geoalchemy2` ويفترض أنك تستخدم قاعدة بيانات مع تمكين PostGIS.

أفضل الممارسات لاستخدام الخصائص الهجينة

• اجعلها بسيطة: استخدم الخصائص الهجينة للحسابات البسيطة نسبيًا. للمنطق الأكثر تعقيدًا، فكر في استخدام دوال أو أساليب منفصلة.
• استخدم أنواع البيانات المناسبة: تأكد من أن أنواع البيانات المستخدمة في خصائصك الهجينة متوافقة مع كل من Python و SQL.
• ضع الأداء في الاعتبار: بينما يمكن للخصائص الهجينة تحسين الأداء عن طريق إجراء العمليات الحسابية في قاعدة البيانات، فمن الضروري مراقبة أداء استعلاماتك وتحسينها حسب الحاجة.
• اختبر بدقة: اختبر خصائصك الهجينة بدقة للتأكد من أنها تنتج النتائج الصحيحة في جميع السياقات.
• وثّق الكود الخاص بك: وثّق خصائصك الهجينة بوضوح لشرح ما تفعله وكيف تعمل.

الأخطاء الشائعة وكيفية تجنبها

• الدوال الخاصة بقاعدة البيانات: تأكد من أن دوال التعبير الخاصة بك تستخدم دوال مستقلة عن قاعدة البيانات أو توفر تطبيقات خاصة بقاعدة البيانات لتجنب مشكلات التوافق.
• دوال التعبير غير الصحيحة: تحقق جيدًا من أن دوال التعبير الخاصة بك تترجم خاصيتك الهجينة بشكل صحيح إلى تعبير SQL صالح.
• اختناقات الأداء: تجنب استخدام الخصائص الهجينة للحسابات المعقدة جدًا أو التي تستهلك الكثير من الموارد، حيث يمكن أن يؤدي ذلك إلى اختناقات في الأداء.
• الأسماء المتعارضة: تجنب استخدام نفس الاسم لخاصيتك الهجينة وعمود في نموذجك، حيث يمكن أن يؤدي ذلك إلى الارتباك والأخطاء.

اعتبارات التدويل (Internationalization)

عند العمل مع الخصائص الهجينة في التطبيقات الدولية، ضع في اعتبارك ما يلي:

• تنسيقات التاريخ والوقت: استخدم تنسيقات التاريخ والوقت المناسبة للمناطق المختلفة.
• تنسيقات الأرقام: استخدم تنسيقات الأرقام المناسبة للمناطق المختلفة، بما في ذلك فواصل العشرية وفواصل الآلاف.
• تنسيقات العملات: استخدم تنسيقات العملات المناسبة للمناطق المختلفة، بما في ذلك رموز العملات والمنازل العشرية.
• مقارنات السلاسل النصية: استخدم دوال مقارنة السلاسل النصية التي تراعي الإعدادات المحلية لضمان مقارنة السلاسل بشكل صحيح في لغات مختلفة.

على سبيل المثال، عند حساب العمر، ضع في اعتبارك تنسيقات التاريخ المختلفة المستخدمة حول العالم. في بعض المناطق، يُكتب التاريخ على النحو `MM/DD/YYYY`، بينما في مناطق أخرى يكون `DD/MM/YYYY` أو `YYYY-MM-DD`. تأكد من أن الكود الخاص بك يحلل التواريخ بشكل صحيح بجميع التنسيقات.

عند دمج السلاسل النصية (كما في مثال `full_name`)، كن على دراية بالاختلافات الثقافية في ترتيب الأسماء. في بعض الثقافات، يأتي اسم العائلة قبل الاسم الأول. فكر في توفير خيارات للمستخدمين لتخصيص تنسيق عرض الاسم.

الخاتمة

خصائص SQLAlchemy الهجينة هي أداة قوية لإنشاء سمات محسوبة داخل نماذج البيانات الخاصة بك. تتيح لك التعبير عن العلاقات والحسابات المعقدة مباشرة في نماذجك، مما يحسن من قابلية قراءة الكود وصيانته وكفاءته. من خلال فهم كيفية تحديد الخصائص الهجينة ودوال التعبير ودوال التعيين والحذف، يمكنك الاستفادة من هذه الميزة لبناء تطبيقات أكثر تطورًا وقوة.

باتباع أفضل الممارسات الموضحة في هذا المقال وتجنب الأخطاء الشائعة، يمكنك استخدام الخصائص الهجينة بفعالية لتعزيز نماذج SQLAlchemy الخاصة بك وتبسيط منطق الوصول إلى البيانات. تذكر أن تأخذ في الاعتبار جوانب التدويل لضمان عمل تطبيقك بشكل صحيح للمستخدمين في جميع أنحاء العالم. مع التخطيط والتنفيذ الدقيقين، يمكن أن تصبح الخصائص الهجينة جزءًا لا يقدر بثمن من مجموعة أدوات SQLAlchemy الخاصة بك.